Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/api-reference/sourcebot-public.openapi.json`:
- Around line 8-13: The OpenAPI document currently exposes a local-only server
("servers" -> url "http://localhost:3000"), which will be embedded into
generated clients; update the "servers" entry in the API spec by either removing
the entire "servers" array or replacing the localhost URL with a deploy-safe
default (e.g., a production or placeholder base URL such as
"https://api.example.com" or a templated variable) so generated clients/tooling
don't default to localhost; ensure you modify the "servers" array in the
top-level OpenAPI object to reflect this change.
- Around line 444-448: The description of the PublicStreamSearchSse type
references a missing schema PublicStreamedSearchEvent in components.schemas;
either add a proper schema definition for PublicStreamedSearchEvent (and any
sub-event variants like "chunk"/"done" you expect) into the source OpenAPI model
so components.schemas.PublicStreamedSearchEvent exists and describes the SSE
JSON frame shape, and ensure the generator/template picks up that schema, or
remove/replace the dangling name from PublicStreamSearchSse.description in the
source document so it does not reference a non-existent schema; update the
source generator templates if necessary so generated docs include
components.schemas.PublicStreamedSearchEvent.

In `@docs/docs/api-reference/overview.mdx`:
- Around line 6-8: Rewrite the opening paragraph so it leads with the runtime
spec URL "/api/openapi.json" (instead of the static docs artifact
"/api-reference/sourcebot-public.openapi.json"), use second person ("you") and
present tense, and keep sentences short and direct; specifically update the
lines that currently say "Sourcebot exposes a public REST API..." and the
sentence mentioning the Mintlify-rendered file so they start by telling the
reader to use "/api/openapi.json" on their instance, and state that the endpoint
reference is generated from Zod schemas/OpenAPI registry and rendered by
Mintlify in plain, actionable language.

---

Nitpick comments:
In `@packages/web/src/openapi/publicApiDocument.ts`:
- Around line 232-238: The OpenAPI document's servers array currently only lists
the local entry; update the servers array in publicApiDocument to include
additional entries for production/cloud (e.g., a production URL and a
templated/placeholder like {baseUrl}) so consumers see expected deployment
endpoints. Modify the servers array where it's defined (the variable/object
containing servers and tags: [searchTag, reposTag, filesTag, miscTag]) to add a
production URL and/or a URL template with a description and optional variables
(e.g., baseUrl) so clients can substitute their environment; ensure descriptions
clearly label development vs production entries.
- Around line 24-46: Add a short inline comment above the manual SchemaObject
definitions explaining why they are hand-written: publicFileTreeNodeSchema
(recursive/self-referential children) and publicGetTreeResponseSchema cannot be
generated from the Zod types because zod-to-openapi does not handle recursive
schemas; state that this is intentional and link or note zod-to-openapi's
limitation to aid future maintainers.

In `@packages/web/src/openapi/publicApiSchemas.ts`:
- Around line 18-23: Keep the current safe pattern: leave the module-scoped
guard (hasExtendedZod) and the call to extendZodWithOpenApi(z) as-is so the Zod
extension runs exactly once within this module; ensure you don't remove
hasExtendedZod or introduce another extension call elsewhere (refer to
hasExtendedZod, extendZodWithOpenApi, and z) — if you prefer a refactor later,
move the same guarded logic into a dedicated initialization module, but no
functional change is needed now.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@CHANGELOG.md`:
- Around line 10-13: Update the changelog entry that currently reads "Added
generated OpenAPI documentation for the public search, repo, and file browsing
API surface. [`#101`]" to use the correct pull request id "[`#996`]" and move this
line from the "### Changed" section into the "### Added" section; ensure the
entry ends with " [`#996`]" and that the "### Added" header contains this line
while removing it from "### Changed".

In `@packages/web/src/openapi/publicApiDocument.ts`:
- Around line 225-239: The OpenAPI document currently lacks security
definitions; after generator.generateDocument(...) add a securitySchemes entry
under document.components (e.g., document.components.securitySchemes = {
bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } }) and set a
global document.security (e.g., document.security = [{ bearerAuth: [] }]) so
clients know to send credentials; keep per-operation overrides (clear security
on truly unauthenticated endpoints) rather than leaving endpoints anonymous. Use
the existing symbols document, document.components, and
generator.generateDocument to locate where to add these fields and add/merge
them alongside the existing schemas logic that sets document.components.schemas
and PublicFileTreeNode.

In `@packages/web/src/openapi/publicApiSchemas.ts`:
- Around line 41-46: publicVersionResponseSchema currently pins the example for
the version field to a hard-coded string which drifts from the actual build;
update the z.object for publicVersionResponseSchema so the version example is
either removed or set dynamically (e.g., use the app/build version constant)
instead of the literal 'v4.15.2' — locate publicVersionResponseSchema and the
nested version field in publicApiSchemas.ts and replace the static example with
a dynamic value pulled from your build/version export or drop the example
entirely.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/release-prod.yml:
- Around line 134-138: The workflow runs "Install dependencies" and "Generate
OpenAPI docs" while the repo remote has the write-scoped GitHub App token
persisted; change the checkout/credential handling so these steps run without
persisted credentials: set the actions/checkout used before the "Install
dependencies" and "Generate OpenAPI docs" steps to persist-credentials: false
(or use a read-only checkout action), and only configure/inject the write-scoped
app token immediately before the step that performs the git push (e.g., the step
that calls git push or "Release" logic). Ensure the checkout used for the push
step has persist-credentials true or re-checkout with the token injected so only
the final push runs with write access.

In `@docs/api-reference/sourcebot-public.openapi.json`:
- Around line 141-148: Change discrete numeric schema types from "number" to
"integer" for fields representing counts/IDs/positions—specifically update
"byteOffset", "lineNumber", and "column" (and other discrete fields like IDs,
status codes, pagination/count fields) to use "type": "integer" and add
"format": "int32" or "int64" where appropriate in the OpenAPI generator output;
update the generator/template that emits these properties so all occurrences
(e.g., other count/id/position schemas referenced in the spec) are emitted as
integer types rather than floating-point numbers.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/web/src/app/api/`(server)/openapi.json/route.ts:
- Around line 8-15: Resolve the OpenAPI file path from process.cwd() into the
container's /app docs (use path.join(process.cwd(), 'docs', 'api-reference',
'sourcebot-public.openapi.json') instead of '../../docs/...') when constructing
openApiPath, and change the ENOENT catch branch in the JSON read/parse block
(the JSON.parse(await fs.readFile(...)) try/catch around openApiPath) to not
silently swallow the error: either rethrow or throw a new explicit error (e.g.,
"OpenAPI document not found") so the handler returns an error/404 instead of a
successful empty response; apply the same path and ENOENT handling fix to the
analogous block referenced at lines 19-25.

---

Nitpick comments:
In `@packages/web/src/app/api/`(server)/openapi.json/route.ts:
- Around line 18-26: Add explicit query validation at the top of the exported
GET handler: create a Zod empty object schema (e.g., const querySchema =
z.object({})) and validate the incoming request query against it before calling
loadOpenApiDocument(); on validation failure return the existing
queryParamsSchemaValidationError with the Zod error. Import z from 'zod' and
queryParamsSchemaValidationError, perform the parse/parseAsync on the request's
query/searchParams inside the async function exported as GET (the handler passed
to apiHandler), and only proceed to call loadOpenApiDocument() and return
Response.json(...) when validation succeeds.